home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / elispman.lha / elispman / calendar.texi < prev    next >
Lisp/Scheme  |  1993-05-19  |  33KB  |  864 lines

  1. @c -*-texinfo-*-
  2. @c This is part of the GNU Emacs Lisp Reference Manual.
  3. @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. 
  4. @c See the file elisp.texi for copying conditions.
  5. @node Calendar, Tips, Emacs Display, Top
  6. @chapter Customizing the Calendar and Diary
  7.  
  8.   There are many customizations that you can use to make the calendar and
  9. diary suit your personal tastes.
  10.  
  11. @menu
  12. * Calendar Customizing::   Defaults you can set.
  13. * Holiday Customizing::    Defining your own holidays.
  14. * Date Display Format::    Changing the format.
  15. * Time Display Format::    Changing the format.
  16. * Daylight Savings::       Changing the default.
  17. * Diary Customizing::      Defaults you can set.
  18. * Hebrew/Islamic Entries:: How to obtain them.
  19. * Fancy Diary Display::    Enhancing the diary display, sorting entries.
  20. * Included Diary Files::   Sharing a common diary file.
  21. * Sexp Diary Entries::     Fancy things you can do.
  22. * Appt Customizing::       Customizing appointment reminders.
  23. @end menu
  24.  
  25. @node Calendar Customizing
  26. @section Customizing the Calendar
  27. @vindex view-diary-entries-initially
  28.  
  29.   If you set the variable @code{view-diary-entries-initially} to
  30. @code{t}, calling up the calendar automatically displays the diary
  31. entries for the current date as well.  The diary dates appear only if
  32. the current date is visible.  If you add both of the following lines to
  33. your @file{.emacs} file:@refill
  34.  
  35. @example
  36. (setq view-diary-entries-initially t)
  37. (calendar)
  38. @end example
  39.  
  40. @noindent
  41. they display both the calendar and diary windows whenever you start Emacs.
  42.  
  43. @vindex view-calendar-holidays-initially
  44.   Similarly, if you set the variable
  45. @code{view-calendar-holidays-initially} to @code{t}, entering the
  46. calendar automatically displays a list of holidays for the current three
  47. month period.  The holiday list appears in a separate window.@refill
  48.  
  49. @vindex mark-diary-entries-in-calendar
  50.   You can set the variable @code{mark-diary-entries-in-calendar} to @code{t}
  51. in order to place a plus sign (@samp{+}) beside any dates with diary entries.
  52. Whenever the calendar window is displayed or redisplayed, the diary entries
  53. are automatically marked for holidays.
  54.  
  55. @vindex mark-holidays-in-calendar
  56.   Similarly, setting the variable @code{mark-holidays-in-calendar} to
  57. @code{t} places an asterisk (@samp{*}) after all holiday dates visible
  58. in the calendar window.
  59.  
  60. @vindex calendar-load-hook
  61.   There are many customizations that you can make with the hooks
  62. provided.  For example, the variable @code{calendar-load-hook}, whose
  63. default value is @code{nil}, is a normal hook run when the calendar
  64. package is first loaded (before actually starting to display the
  65. calendar).
  66.  
  67. @vindex initial-calendar-window-hook
  68.   The variable @code{initial-calendar-window-hook}, whose default value
  69. is @code{nil}, is a normal hook run the first time the calendar window
  70. is displayed.  The function is invoked only when you first enter
  71. Calendar mode, not when you redisplay an existing Calendar window.  But
  72. if you leave the calendar with the @kbd{q} command and reenter it, the
  73. hook runs again.@refill
  74.  
  75. @vindex today-visible-calendar-hook
  76.   The variable @code{today-visible-calendar-hook}, whose default value
  77. is @code{nil}, is a normal hook run after the calendar buffer has been
  78. prepared with the calendar when the current date is visible in the
  79. window.  One use of this hook is to replace today's date with asterisks;
  80. a function @code{calendar-star-date} is included for this purpose.  In
  81. your @file{.emacs} file, put:@refill
  82.  
  83. @findex calendar-star-date
  84. @example
  85. (setq today-visible-calendar-hook 'calendar-star-date)
  86. @end example
  87.  
  88. @noindent
  89. Another standard hook function adds asterisks around the current date.
  90. Here's how to use it:
  91.  
  92. @findex calendar-mark-today
  93. @example
  94. (setq today-visible-calendar-hook 'calendar-mark-today)
  95. @end example
  96.  
  97. @vindex today-invisible-calendar-hook
  98. @noindent
  99.   A corresponding variable, @code{today-invisible-calendar-hook}, whose
  100. default value is @code{nil}, is a normal hook run after the calendar
  101. buffer text has been prepared, if the current date is @emph{not} visible
  102. in the window.@refill
  103.  
  104. @node Holiday Customizing
  105. @section Customizing the Holidays
  106.  
  107. @vindex calendar-holidays
  108. @vindex christian-holidays
  109. @vindex hebrew-holidays
  110. @vindex islamic-holidays
  111.   Emacs knows about holidays defined by entries on one of several lists.
  112. You can customize theses lists of holidays to your own needs, adding
  113. holidays or deleting lists of holidays.  The lists of holidays that
  114. Emacs uses are for general holidays (@code{general-holidays}), local
  115. holidays (@code{local-holidays}), Christian holidays
  116. (@code{christian-holidays}), Hebrew (Jewish) holidays
  117. (@code{hebrew-holidays}), Islamic (Moslem) holidays
  118. (@code{islamic-holidays}), and other holidays (@code{other-holidays}).
  119.  
  120. @vindex general-holidays
  121.   The general holidays are, by default, holidays common throughout the
  122. United States.  To eliminate these holidays, set @code{general-holidays}
  123. to @code{nil}.
  124.  
  125. @vindex local-holidays
  126.   There are no default local holidays (but sites may supply some).  You
  127. can set the variable @code{local-holidays} to any list of holidays, as
  128. described below.
  129.  
  130. @vindex all-christian-calendar-holidays
  131. @vindex all-hebrew-calendar-holidays
  132. @vindex all-islamic-calendar-holidays
  133.   By default, Emacs does not consider all the holidays of these
  134. religions, only those commonly found in secular calendars.  For a more
  135. extensive collection of religious holidays, you can set any (or all) of
  136. the variables @code{all-christian-calendar-holidays},
  137. @code{all-hebrew-calendar-holidays}, or
  138. @code{all-islamic-calendar-holidays} to @code{t}.  If you want to
  139. eliminate the religious holidays, set any or all of the corresponding
  140. variables @code{christian-holidays}, @code{hebrew-holidays}, and
  141. @code{islamic-holidays} to @code{nil}.@refill
  142.  
  143. @vindex other-holidays
  144.   You can set the variable @code{other-holidays} to any list of
  145. holidays.  This list, normally empty, is intended for your use.
  146.  
  147. @cindex holiday forms
  148.   Each of the lists (@code{general-holidays}), (@code{local-holidays}),
  149. (@code{christian-holidays}), (@code{hebrew-holidays}),
  150. (@code{islamic-holidays}),and (@code{other-holidays}) is a list of
  151. @dfn{holiday forms}, each holiday form describing a holiday (or
  152. sometimes a list of holidays).  Holiday forms may have the following
  153. formats:
  154.  
  155. @table @code
  156. @item (fixed @var{month} @var{day} @var{string})
  157. A fixed date on the Gregorian calendar.  @var{month} and @var{day} are
  158. numbers, @var{string} is the name of the holiday.
  159.  
  160. @item (float @var{month} @var{dayname} @var{k} @var{string})
  161. The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar
  162. (@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back
  163. from the end of the month.  @var{string} is the name of the holiday.
  164.  
  165. @item (hebrew @var{month} @var{day} @var{string})
  166. A fixed date on the Hebrew calendar.  @var{month} and @var{day} are
  167. numbers, @var{string} is the name of the holiday.
  168.  
  169. @item (islamic @var{month} @var{day} @var{string})
  170. A fixed date on the Islamic calendar.  @var{month} and @var{day} are
  171. numbers, @var{string} is the name of the holiday.
  172.  
  173. @item (julian @var{month} @var{day} @var{string})
  174. A fixed date on the Julian calendar.  @var{month} and @var{day} are
  175. numbers, @var{string} is the name of the holiday.
  176.  
  177. @item (sexp @var{sexp} @var{string})
  178. @var{sexp} is a Lisp expression that should use the variable @code{year}
  179. to compute the date of a holiday, or @code{nil} if the holiday doesn't
  180. happen this year.  The value represents the date as a list of the form
  181. @code{(@var{month} @var{day} @var{year})}.  @var{string} is the name of
  182. the holiday.
  183.  
  184. @item (if @var{boolean} @var{holiday-form} &optional @var{holiday-form})
  185. A choice between two holidays based on the value of @var{boolean}.
  186.  
  187. @item (@var{function} &optional @var{args})
  188. Dates requiring special computation; @var{args}, if any, are passed in
  189. a list to the function @code{calendar-holiday-function-@var{function}}.
  190. @end table
  191.  
  192.   For example, suppose you want to add Bastille Day, celebrated in
  193. France on July 14.  You can do this by adding the following line
  194. to your @file{.emacs} file:
  195.  
  196. @example
  197. (setq other-holidays '((fixed 7 14 "Bastille Day")))
  198. @end example
  199.  
  200. @noindent
  201. The holiday form @code{(fixed 7 14 "Bastille Day")} specifies the
  202. fourteenth day of the seventh month (July).
  203.  
  204.   Many holidays occur on a specific day of the week, at a specific time
  205. of month.  Here is a holiday form describing Hurricane Supplication Day,
  206. celebrated in the Virgin Islands on the fourth Monday in August:
  207.  
  208. @example
  209. (float 8 1 4 "Hurricane Supplication Day")
  210. @end example
  211.  
  212. @noindent
  213. Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
  214. Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
  215. the month (1 specifies the first occurrence, 2 the second occurrence,
  216. @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and
  217. so on).
  218.  
  219.   You can specify holidays that occur on fixed days of the Hebrew,
  220. Islamic, and Julian calendars too.  For example,
  221.  
  222. @example
  223. (setq other-holidays
  224.       '((hebrew 10 2 "Last day of Hanukkah")
  225.         (islamic 3 12 "Mohammed's Birthday")
  226.         (julian 4 2 "Jefferson's Birthday")))
  227. @end example
  228.  
  229. @noindent
  230. adds the last day of Hanukkah (since the Hebrew months are numbered with
  231. 1 starting from Nisan), the Islamic feast celebrating Mohammed's
  232. birthday (since the Islamic months are numbered from 1 starting with
  233. Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
  234. Julian calendar.
  235.  
  236.   To include a holiday conditionally, use either the @samp{if} or the
  237. @samp{sexp} form.  For example, American presidential elections occur on
  238. the first Tuesday after the first Monday in November of years divisible
  239. by 4:
  240.  
  241. @example
  242. (sexp (if (= 0 (% year 4))
  243.           (calendar-gregorian-from-absolute
  244.             (1+ (calendar-dayname-on-or-before
  245.                    1 (+ 6 (calendar-absolute-from-gregorian
  246.                             (list 11 1 year))))))
  247.       "US Presidential Election"))
  248. @end example
  249.  
  250. @noindent
  251. or
  252.  
  253. @example
  254. (if (= 0 (% displayed-year 4))
  255.     (fixed 11
  256.            (extract-calendar-day
  257.              (calendar-gregorian-from-absolute
  258.                (1+ (calendar-dayname-on-or-before
  259.                      1 (+ 6 (calendar-absolute-from-gregorian
  260.                               (list 11 1 displayed-year)))))))
  261.            "US Presidential Election"))
  262. @end example
  263.  
  264.   Some holidays just don't fit into any of these forms because special
  265. calculations are involved in their determination.  In such cases you
  266. must write a Lisp function to do the calculation.  The function should
  267. return a (possibly empty) list of the relevant Gregorian dates among the
  268. range visible in the calendar window, with descriptive strings, like
  269. this:
  270.  
  271. @example
  272. (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
  273. @end example
  274.  
  275. @node Date Display Format
  276. @section Date Display Format
  277. @vindex calendar-date-display-form
  278.  
  279.   You can customize the manner of displaying dates in the diary,
  280. in mode lines, and in messages by setting
  281. @code{calendar-date-display-form}.  This variable is a list of
  282. expressions that can involve the variables @code{month}, @code{day}, and
  283. @code{year}, all numbers in string form, and @code{monthname} and
  284. @code{dayname}, both alphabetic strings.  In the American style, the
  285. default value of this list is as follows:
  286.  
  287. @example
  288. ((if dayname (concat dayname ", ")) monthname " " day ", " year)
  289. @end example
  290.  
  291. @noindent
  292. while in the European style this value is the default:
  293.  
  294. @example
  295. ((if dayname (concat dayname ", ")) day " " monthname " " year)
  296. @end example
  297.  
  298. The ISO standard date representation is this:
  299.  
  300. @example
  301. (year "-" month "-" day)
  302. @end example
  303.  
  304. @noindent
  305. This specifies a typical American format:
  306.  
  307. @example
  308. (month "/" day "/" (substring year -2))
  309. @end example
  310.  
  311. @node Time Display Format
  312. @section Time Display Format
  313. @vindex calendar-time-display-form
  314.  
  315.   In the calendar, diary, and related buffers, Emacs displays times of
  316. day in the conventional American style with the hours from 1 through 12,
  317. minutes, and either @samp{am} or @samp{pm}.  If you prefer the
  318. ``military'' (European) style of writing times---in which the hours go
  319. from 00 to 23---you can alter the variable
  320. @code{calendar-time-display-form}.  This variable is a list of
  321. expressions that can involve the variables @code{12-hours},
  322. @code{24-hours}, and @code{minutes}, all numbers in string form, and
  323. @code{am-pm} and @code{time-zone}, both alphabetic strings.  The default
  324. definition of @code{calendar-time-display-form} is as follows:
  325.  
  326. @example
  327. (12-hours ":" minutes am-pm (if time-zone " (") time-zone (if time-zone ")"))
  328. @end example
  329.  
  330.   Setting @code{calendar-time-display-form} to
  331.  
  332. @example
  333. (24-hours ":" minutes (if time-zone " (") time-zone (if time-zone ")"))
  334. @end example
  335.  
  336. @noindent
  337. gives military-style times like @samp{21:07 (UT)} if time zone names are
  338. defined, and times like @samp{21:07} if they are not.
  339.  
  340. @node Daylight Savings
  341. @section Daylight Savings Time
  342. @cindex daylight savings time
  343. @vindex calendar-daylight-savings-starts
  344. @vindex calendar-daylight-savings-ends
  345.  
  346.   Emacs understands the difference between standard time and daylight
  347. savings time---the times given for sunrise, sunset, solstices,
  348. equinoxes, and the phases of the moon take that into account.  The
  349. default starting and stopping dates for daylight savings time are the
  350. present-day American rules of the first Sunday in April until the last
  351. Sunday in October, but you can specify whatever rules you want by
  352. setting @code{calendar-daylight-savings-starts} and
  353. @code{calendar-daylight-savings-ends}.  Their values should be Lisp
  354. expressions that refer to the variable @code{year}, and evaluate to the
  355. Gregorian date on which daylight savings time starts or (respectively)
  356. ends, in the form of a list @code{(@var{month} @var{day} @var{year})}.
  357.  
  358.   Emacs uses these expressions to determine the starting date of
  359. daylight savings time for the holiday list and for correcting times of
  360. day in the solar and lunar calculations.
  361.  
  362.   The default value of @code{calendar-daylight-savings-starts} is this,
  363.  
  364. @example
  365. (calendar-nth-named-day 1 0 4 year)
  366. @end example
  367.  
  368. @noindent
  369. which computes the first 0th day (Sunday) of the fourth month (April) in
  370. the year specified by @code{year}.  If daylight savings time were
  371. changed to start on October 1, you would set
  372. @code{calendar-daylight-savings-starts} to
  373.  
  374. @example
  375. (list 10 1 year)
  376. @end example
  377.  
  378.   For a more complex example, suppose daylight savings time begins on
  379. the first of Nisan on the Hebrew calendar.  You would set
  380. @code{calendar-daylight-savings-starts} to
  381.  
  382. @example
  383. (calendar-gregorian-from-absolute
  384.   (calendar-absolute-from-hebrew
  385.     (list 1 1 (+ year 3760))))
  386. @end example
  387.  
  388. @noindent
  389. because Nisan is the first month in the Hebrew calendar and the Hebrew
  390. year differs from the Gregorian year by 3760 at Nisan.
  391.  
  392.   If there is no daylight savings time at your location, or if you want
  393. all times in standard time, set @code{calendar-daylight-savings-starts} and
  394. @code{calendar-daylight-savings-ends} to @code{nil}.
  395.  
  396. @node Diary Customizing
  397. @section Customizing the Diary
  398.  
  399. @vindex holidays-in-diary-buffer
  400.   Ordinarily, the mode line of the diary buffer window indicates any
  401. holidays that fall on the date of the diary entries.  The process of
  402. checking for holidays can take several seconds, so including holiday
  403. information delays the display of the diary buffer noticeably.  If you'd
  404. prefer to have a faster display of the diary buffer but without the
  405. holiday information, set the variable @code{holidays-in-diary-buffer} to
  406. @code{nil}.@refill
  407.  
  408. @vindex number-of-diary-entries
  409.   The variable @code{number-of-diary-entries} controls the number of
  410. days of diary entries to be displayed at one time.  It affects the
  411. initial display when @code{view-diary-entries-initially} is @code{t}, as
  412. well as the command @kbd{M-x diary}.  For example, the default value is
  413. 1, which says to display only the current day's diary entries.  If the
  414. value is 2, both the current day's and the next day's entries are
  415. displayed.  The value can also be a vector of seven elements: if the
  416. value is @code{[0 2 2 2 2 4 1]} then no diary entries appear on Sunday,
  417. the current date's and the next day's diary entries appear Monday
  418. through Thursday, Friday through Monday's entries appear on Friday,
  419. while on Saturday only that day's entries appear.
  420.  
  421. @vindex print-diary-entries-hook
  422. @findex print-diary-entries
  423.   The variable @code{print-diary-entries-hook} is a normal hook run
  424. after preparation of a temporary buffer containing just the diary
  425. entries currently visible in the diary buffer.  (The other, irrelevant
  426. diary entries are really absent from the temporary buffer; in the diary
  427. buffer, they are merely hidden.)  The default value of this hook does
  428. the printing with the command @code{lpr-buffer}.  If you want to use a
  429. different command to do the printing, just change the value of this
  430. hook.  Other uses might include, for example, rearranging the lines into
  431. order by day and time.
  432.  
  433. @vindex diary-date-forms
  434.   You can customize the form of dates in your diary file, if neither the
  435. standard American nor European styles suits your needs, by setting the
  436. variable @code{diary-date-forms}.  This variable is a list of forms of
  437. dates recognized in the diary file.  Each form is a list of regular
  438. expressions (@pxref{Regular Expressions}) and the variables
  439. @code{month}, @code{day}, @code{year}, @code{monthname}, and
  440. @code{dayname}.  The variable @code{monthname} matches the name of the
  441. month, capitalized or not, or its three-letter abbreviation, followed by
  442. a period or not; it matches @samp{*}.  Similarly, @code{dayname} matches
  443. the name of the day, capitalized or not, or its three-letter
  444. abbreviation, followed by a period or not.  The variables @code{month},
  445. @code{day}, and @code{year} match those numerical values, preceded by
  446. arbitrarily many zeros; they also match @samp{*}.  The default value of
  447. @code{diary-date-forms} in the American style is
  448.  
  449. @example
  450. ((month "/" day "[^/0-9]")
  451.  (month "/" day "/" year "[^0-9]")
  452.  (monthname " *" day "[^,0-9]")
  453.  (monthname " *" day ", *" year "[^0-9]")
  454.  (dayname "\\W"))
  455. @end example
  456.  
  457. @noindent
  458. Emacs matches of the diary entries with the date forms is done with the
  459. standard syntax table from Fundamental mode (@pxref{Syntax Tables}), but
  460. with the @samp{*} changed so that it is a word constituent.
  461.  
  462.   The forms on the list must be @emph{mutually exclusive} and must not
  463. match any portion of the diary entry itself, just the date.  If, to be
  464. mutually exclusive, the pattern must match a portion of the diary entry
  465. itself, the first element of the form @emph{must} be @code{backup}.
  466. This causes the date recognizer to back up to the beginning of the
  467. current word of the diary entry.  Even if you use @code{backup}, the
  468. form must absolutely not match more than a portion of the first word of
  469. the diary entry.  The default value of @code{diary-date-forms} in the
  470. European style is this list:
  471.  
  472. @example
  473. ((day "/" month "[^/0-9]")
  474.  (day "/" month "/" year "[^0-9]")
  475.  (backup day " *" monthname "\\W+\\<[^*0-9]")
  476.  (day " *" monthname " *" year "[^0-9]")
  477.  (dayname "\\W"))
  478. @end example
  479.  
  480. @noindent
  481. Notice the use of @code{backup} in the middle form because part of the
  482. diary entry must be matched to distinguish this form from the following one.
  483.  
  484. @node Hebrew/Islamic Entries
  485. @section Hebrew- and Islamic-Date Diary Entries
  486.  
  487.   Your diary file can have entries based on Hebrew or Islamic dates, as
  488. well as entries based on our usual Gregorian calendar.  However, because
  489. the processing of such entries is time-consuming and most people don't
  490. need them, you must customize the processing of your diary file to
  491. specify that you want such entries recognized.  If you want Hebrew-date
  492. diary entries, for example, you must include these lines in your
  493. @file{.emacs} file:
  494.  
  495. @vindex nongregorian-diary-listing-hook
  496. @vindex nongregorian-diary-marking-hook
  497. @findex list-hebrew-diary-entries
  498. @findex mark-hebrew-diary-entries
  499. @example
  500. (setq nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
  501. (setq nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
  502. @end example
  503.  
  504. @noindent
  505. If you want Islamic-date entries, include these lines in your
  506. @file{.emacs} file:
  507.  
  508. @findex list-islamic-diary-entries
  509. @findex mark-islamic-diary-entries
  510. @example
  511. (setq nongregorian-diary-listing-hook 'list-islamic-diary-entries)
  512. (setq nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
  513. @end example
  514.  
  515. @noindent
  516. If you want both Hebrew- and Islamic-date entries, include these lines:
  517.  
  518. @example
  519. (setq nongregorian-diary-listing-hook
  520.       '(list-hebrew-diary-entries list-islamic-diary-entries))
  521. (setq nongregorian-diary-marking-hook
  522.       '(mark-hebrew-diary-entries mark-islamic-diary-entries))
  523. @end example
  524.  
  525.   Hebrew- and Islamic-date diary entries have the same formats as
  526. Gregorian-date diary entries, except that the date must be preceded with
  527. an @samp{H} for Hebrew dates and an @samp{I} for Islamic dates.
  528. Moreover, because the Hebrew and Islamic month names are not uniquely
  529. specified by the first three letters, you may not abbreviate them.  For
  530. example, a diary entry for the Hebrew date Heshvan 25 could look like
  531.  
  532. @example
  533. HHeshvan 25 Happy Hebrew birthday!
  534. @end example
  535.  
  536. @noindent
  537. and would appear in the diary for any date that corresponds to Heshvan 25
  538. on the Hebrew calendar.  Similarly, an Islamic-date diary entry might be
  539.  
  540. @example
  541. IDhu al-Qada 25 Happy Islamic birthday!
  542. @end example
  543.  
  544. @noindent
  545. and would appear in the diary for any date that corresponds to Dhu al-Qada 25
  546. on the Islamic calendar.
  547.  
  548.   As with Gregorian-date diary entries, Hebrew- and Islamic-date entries
  549. are nonmarking if they are preceded with an ampersand (@samp{&}).
  550.  
  551.   There are commands to help you in making Hebrew- and Islamic-date
  552. entries to your diary:
  553.  
  554. @table @kbd
  555. @item i h d
  556. Add a diary entry for the Hebrew date corresponding to the selected date
  557. (@code{insert-hebrew-diary-entry}).
  558. @item i h m
  559. Add a diary entry for the day of the Hebrew month corresponding to the
  560. selected date (@code{insert-monthly-hebrew-diary-entry}).
  561. @item i h y
  562. Add a diary entry for the day of the Hebrew year corresponding to the
  563. selected date (@code{insert-yearly-hebrew-diary-entry}).
  564. @item i i d
  565. Add a diary entry for the Islamic date corresponding to the selected date
  566. (@code{insert-islamic-diary-entry}).
  567. @item i i m
  568. Add a diary entry for the day of the Islamic month corresponding to the
  569. selected date (@code{insert-monthly-islamic-diary-entry}).
  570. @item i i y
  571. Add a diary entry for the day of the Islamic year corresponding to the
  572. selected date (@code{insert-yearly-islamic-diary-entry}).
  573. @end table
  574.  
  575. @findex insert-hebrew-diary-entry
  576. @findex insert-monthly-hebrew-diary-entry
  577. @findex insert-yearly-hebrew-diary-entry
  578. @findex insert-islamic-diary-entry
  579. @findex insert-monthly-islamic-diary-entry
  580. @findex insert-yearly-islamic-diary-entry
  581.   These commands work exactly like the corresponding commands for ordinary
  582. diary entries: Move point to a date in the calendar window and the above
  583. commands insert the Hebrew or Islamic date (corresponding to the date
  584. indicated by point) at the end of your diary file and you can then type the
  585. diary entry.  If you want the diary entry to be nonmarking, give a numeric
  586. argument to the command.
  587.  
  588. @node Fancy Diary Display
  589. @section Fancy Diary Display
  590. @vindex diary-display-hook
  591. @findex simple-diary-display
  592.  
  593.   Diary display works by preparing the diary buffer and then running the
  594. hook @code{diary-display-hook}.  The default value of this hook hides
  595. the irrelevant diary entries and then displays the buffer
  596. (@code{simple-diary-display}).  However, if you specify the hook as
  597. follows,
  598.  
  599. @cindex diary buffer
  600. @findex fancy-diary-display
  601. @example
  602. (add-hook 'diary-display-hook 'fancy-diary-display)
  603. @end example
  604.  
  605. @noindent
  606. then fancy mode displays diary entries and holidays by copying them into
  607. a special buffer that exists only for display.  Copying provides an
  608. opportunity to change the displayed text to make it prettier---for
  609. example, to sort the entries by the dates they apply to.
  610.  
  611.   As with simple diary display, you can print a hard copy of the buffer
  612. with @code{print-diary-entries}.  To print a hard copy of a day-by-day
  613. diary for a week by positioning point on Sunday of that week, type
  614. @kbd{7 d} and then do @kbd{M-x print-diary-entries}.  As usual, the
  615. inclusion of the holidays slows down the display slightly; you can speed
  616. things up by setting the variable @code{holidays-in-diary-buffer} to
  617. @code{nil}.
  618.  
  619. @vindex diary-list-include-blanks
  620.   Ordinarily, the fancy diary buffer does not show days for which there are
  621. no diary entries, even if that day is a holiday.  If you want such days to be
  622. shown in the fancy diary buffer, set the variable
  623. @code{diary-list-include-blanks} to @code{t}.@refill
  624.  
  625. @cindex sorting diary entries
  626.   If you use the fancy diary display, you can use the normal hook
  627. @code{list-diary-entries-hook} to sort each day's diary entries by their
  628. time of day.  Add this line to your @file{.emacs} file:
  629.  
  630. @findex sort-diary-entries
  631. @example
  632. (add-hook 'list-diary-entries-hook 'sort-diary-entries)
  633. @end example
  634.  
  635. @noindent
  636. For each day, this sorts diary entries that begin with a recognizable
  637. time of day according to their times.  Diary entries without times come
  638. first within each day.
  639.  
  640. @node Included Diary Files
  641. @section Included Diary Files
  642.  
  643.   If you use the fancy diary display, you can have diary entries from other
  644. files included with your own by an ``include'' mechanism.  This facility makes
  645. possible the sharing of common diary files among groups of users.  Lines in
  646. the diary file of this form:
  647.  
  648. @example
  649. #include "@var{filename}"
  650. @end example
  651.  
  652. @noindent
  653. includes the diary entries from the file @var{filename} in the fancy
  654. diary buffer (because the ordinary diary buffer is just the buffer
  655. associated with your diary file, you cannot use the include mechanism
  656. unless you use the fancy diary buffer).  The include mechanism is
  657. recursive, by the way, so that included files can include other files,
  658. and so on; you must be careful not to have a cycle of inclusions, of
  659. course.  To enable the include facility, add lines as follows to your
  660. @file{.emacs} file:
  661.  
  662. @vindex list-diary-entries-hook
  663. @vindex mark-diary-entries-hook
  664. @findex include-other-diary-files
  665. @findex mark-included-diary-files
  666. @example
  667. (add-hook 'list-diary-entries-hook 'include-other-diary-files)
  668. (add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
  669. @end example
  670.  
  671. @node Sexp Diary Entries
  672. @section Sexp Entries and the Fancy Diary Display
  673. @cindex sexp diary entries
  674.  
  675.   Sexp diary entries allow you to do more than just have complicated
  676. conditions under which a diary entry applies.  If you use the fancy
  677. diary display, sexp entries can generate the text of the entry depending
  678. on the date itself.  For example, an anniversary diary entry can insert
  679. the number of years since the anniversary date into the text of the
  680. diary entry.  Thus the @samp{%d} in this dairy entry:
  681.  
  682. @findex diary-anniversary
  683. @example
  684. %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
  685. @end example
  686.  
  687. @noindent
  688. gets replaced by the age, so on October 31, 1990 the entry appears in
  689. the fancy diary buffer like this:
  690.  
  691. @example
  692. Arthur's birthday (42 years old)
  693. @end example
  694.  
  695. @noindent
  696. If the diary file instead contains this entry:
  697.  
  698. @example
  699. %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
  700. @end example
  701.  
  702. @noindent
  703. the entry in the fancy diary buffer for October 31, 1990 appears like this:
  704.  
  705. @example
  706. Arthur's 42nd birthday
  707. @end example
  708.  
  709.   Similarly, cyclic diary entries can interpolate the number of repetitions
  710. that have occurred:
  711.  
  712. @findex diary-cyclic
  713. @example
  714. %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
  715. @end example
  716.  
  717. @noindent
  718. looks like this:
  719.  
  720. @example
  721. Renew medication (5th time)
  722. @end example
  723.  
  724. @noindent
  725. in the fancy diary display on September 8, 1990.
  726.  
  727.   The generality of sexp diary entries lets you specify any diary entry
  728. that you can describe algorithmically.  Suppose you get paid on the 21st
  729. of the month if it is a weekday, and to the Friday before if the 21st is
  730. on a weekend.  The diary entry
  731.  
  732. @example
  733. &%%(let ((dayname (calendar-day-of-week date))
  734.          (day (car (cdr date))))
  735.       (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
  736.           (and (memq day '(19 20)) (= dayname 5)))
  737.          ) Pay check deposited
  738. @end example
  739.  
  740. @noindent
  741. applies to just those dates.  This example illustrates how the sexp can
  742. depend on the variable @code{date}; this variable is a list (@var{month}
  743. @var{day} @var{year}) that gives the Gregorian date for which the diary
  744. entries are being found.  If the value of the expression is @code{t},
  745. the entry applies to that date.  If the expression evaluates to
  746. @code{nil}, the entry does @emph{not} apply to that date.
  747.  
  748.   The following sexp diary entries take advantage of the ability (in the fancy
  749. diary display) to concoct diary entries based on the date:
  750.  
  751. @findex diary-sunrise-sunset
  752. @findex diary-phases-of-moon
  753. @findex diary-day-of-year
  754. @findex diary-iso-date
  755. @findex diary-julian-date
  756. @findex diary-astro-day-number
  757. @findex diary-hebrew-date
  758. @findex diary-islamic-date
  759. @findex diary-french-date
  760. @findex diary-mayan-date
  761. @table @code
  762. @item %%(diary-sunrise-sunset)
  763. Make a diary entry for the local times of today's sunrise and sunset.
  764. @item %%(diary-phases-of-moon)
  765. Make a diary entry for the phases (quarters) of the moon.
  766. @item %%(diary-day-of-year)
  767. Make a diary entry with today's day number in the current year and the number
  768. of days remaining in the current year.
  769. @item %%(diary-iso-date)
  770. Make a diary entry with today's equivalent ISO commercial date.
  771. @item %%(diary-julian-date)
  772. Make a diary entry with today's equivalent date on the Julian calendar.
  773. @item %%(diary-astro-day-number)
  774. Make a diary entry with today's equivalent astronomical (Julian) day number.
  775. @item %%(diary-hebrew-date)
  776. Make a diary entry with today's equivalent date on the Hebrew calendar.
  777. @item %%(diary-islamic-date)
  778. Make a diary entry with today's equivalent date on the Islamic calendar.
  779. @item %%(diary-french-date)
  780. Make a diary entry with today's equivalent date on the French Revolutionary
  781. calendar.
  782. @item %%(diary-mayan-date)
  783. Make a diary entry with today's equivalent date on the Mayan calendar.
  784. @end table
  785.  
  786. @noindent
  787. Thus including the diary entry
  788.  
  789. @example
  790. &%%(diary-hebrew-date)
  791. @end example
  792.  
  793. @noindent
  794. causes every day's diary display to contain the equivalent date on the
  795. Hebrew calendar, if you are using the fancy diary display.  (With simple
  796. diary display, the line @samp{&%%(diary-hebrew-date)} appears in the
  797. diary for any date, but does nothing particularly useful.)
  798.  
  799.   There are a number of other available sexp diary entries that are important
  800. to those who follow the Hebrew calendar:
  801.  
  802. @cindex rosh hodesh
  803. @findex diary-rosh-hodesh
  804. @cindex parasha, weekly
  805. @findex diary-parasha
  806. @cindex candle lighting times
  807. @findex diary-sabbath-candles
  808. @cindex omer count
  809. @findex diary-omer
  810. @cindex yahrzeits
  811. @findex diary-yahrzeit
  812. @table @code
  813. @item %%(diary-rosh-hodesh)
  814. Make a diary entry that tells the occurrence and ritual announcement of each
  815. new Hebrew month.
  816. @item %%(diary-parasha)
  817. Make a Saturday diary entry that tells the weekly synagogue scripture reading.
  818. @item %%(diary-sabbath-candles)
  819. Make a Friday diary entry that tells the @emph{local time} of Sabbath
  820. candle lighting.
  821. @item %%(diary-omer)
  822. Make a diary entry that gives the omer count, when appropriate.
  823. @item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name}
  824. Make a diary entry marking the anniversary of a date of death.  The date
  825. is the @emph{Gregorian} (civil) date of death.  The diary entry appears
  826. on the proper Hebrew calendar anniversary and on the day before.  (In
  827. the European style, the order of the parameters is changed to @var{day},
  828. @var{month}, @var{year}.)
  829. @end table
  830.  
  831. @node Appt Customizing
  832. @section Customizing Appointment Reminders
  833.  
  834.   You can specify exactly how Emacs reminds you of an appointment and
  835. how far in advance it begins doing so.  Here are the variables that you
  836. can set:
  837.  
  838. @vindex appt-message-warning-time
  839. @vindex appt-audible
  840. @vindex appt-visible
  841. @vindex appt-display-mode-line
  842. @vindex appt-msg-window
  843. @vindex appt-display-duration
  844. @table @code
  845. @item appt-message-warning-time
  846. The time in minutes before an appointment that the reminder begins.  The
  847. default is 10 minutes.
  848. @item appt-audible
  849. If this is @code{t} (the default), Emacs rings the terminal bell for
  850. appointment reminders.
  851. @item appt-visible
  852. If this is @code{t} (the default), Emacs displays the appointment
  853. message in echo area.
  854. @item appt-display-mode-line
  855. If this is @code{t} (the default), Emacs displays the number of minutes
  856. to the appointment on the mode line.
  857. @item appt-msg-window
  858. If this is @code{t} (the default), Emacs displays the appointment
  859. message in another window.
  860. @item appt-display-duration
  861. The number of seconds an appointment message is displayed.  The default
  862. is 5 seconds.
  863. @end table
  864.